Add MyST-NB for rendering notebooks, and JupySQL for running SQL #566
Conversation
amotl
changed the title
MyST-NB, for rendering Jupyter notebooks
amotl
changed the title
There was a problem hiding this comment.
Looks nice, thanks for the work, checking it in dark mode, https://crate-docs-theme--566.org.readthedocs.build/en/566/myst/notebook-text.html table is hard to read.
|
thanks @surister, using already makes it better, but the alternating table color is not ideal either, maybe this could work? wdyt? |
| "(notebook-traditional)=\n", | ||
| "\n", | ||
| "# Notebook (traditional)\n", | ||
| "\n", | ||
| "The documentation can include traditional Jupyter Notebooks in .ipynb JSON format.\n", | ||
| "They are rendered using [MyST-NB].\n", | ||
| "\n", | ||
| "[MyST-NB]: https://myst-nb.readthedocs.io/\n" |
There was a problem hiding this comment.
FYI: This creates a reference attached to the subsequent headline, as introduced by traditional Sphinx/MyST the other day.
(notebook-traditional)=
# Notebook (traditional)| "source": [ | ||
| "# Notebook (traditional)\n", | ||
| "\n", | ||
| "This is just a placeholder.\n", | ||
| "See {ref}`notebook-traditional` instead." | ||
| ] |
There was a problem hiding this comment.
FYI: This cell's Markdown links to the reference displayed here, using
{ref}`notebook-traditional`
In this spirit, MyST-NB demonstrates that it converges notebooks into real documents, thus they become parts of Sphinx' native document tree, so they can use all the features, including linking between them as if they were traditional reStructuredText or Markdown documents.
| ```{code-cell} ipython3 | ||
| # Run query using JupySQL. | ||
| %reload_ext sql | ||
| %sql sqlite:///population.db | ||
| %sql SELECT * FROM acs2012_5yr_population ORDER BY total_population DESC LIMIT 10; | ||
| ``` |
There was a problem hiding this comment.
Thanks for spotting the dark mode bug here, @surister.
There was a problem hiding this comment.
To conclude this, filing an issue with MyST-NB about it would be perfectly sensible, sharing @msbt's CSS snippet which fixes the problem for us.
/*
Fix dark mode for tables in Jupyter Notebooks rendered by MyST-NB.
https://github.com/crate/crate-docs-theme/pull/566
*/
div.cell_output table {
color: var(--color-content-foreground);
}
div.cell_output tbody tr:nth-child(2n+1) {
background: var(--color-background-hover);
}There was a problem hiding this comment.
[...] filing an issue with MyST-NB about it would be perfectly sensible [...]
In the spirit of upstreaming changes, let me share a few pointers to existing issues about dark mode already (I haven't digested them, so it's really just for reference and information sharing).
- Incorrect "show/hide code cell output" background in dark mode executablebooks/MyST-NB#523
- Code blocks have unreadable white text on white backgrounds in dark mode executablebooks/MyST-NB#607
- MyST-nb injects CSS for ipywidgets that ignores dark mode executablebooks/MyST-NB#618
Also having backlinks on them can help others to resolve the problem in an ad hoc manner, and evaluate our fix, possibly also on other spots than just tables, until a new release of MyST-NB will include a relevant fix. Those have been picked up in the same way:
About
The documentation can now include traditional Jupyter Notebooks in .ipynb format, as well as text-based notebooks written in Markdown, per MyST-NB.
By streamlining running SQL and plotting large datasets in Jupyter Notebooks, CrateDB can provide details closer to what others are offering, per JupySQL.
Details
The patch adds two addons to the documentation stack.
MyST-NB is a gateway from Markdown to IPython/Jupyter: Use MyST-NB for Jupyter Notebook Publishing #449
JupySQL is a gateway from SQL to IPython/Jupyter via
%sql,%%sql, and%sqlplotmagics: https://github.com/crate/tech-writing/issues/415Preview
/cc @karynzv, @hlcianfagna, @hammerhead, @wierdvanderhaar, @ckurze, @msbt, @WalBeh, @simonprickett